---
sidebar_position: 2
---

import CodeBlock from "@theme/CodeBlock";

# Interface

In an effort to make it as easy as possible to create custom chains, we've implemented a ["Runnable"](https://api.js.langchain.com/classes/langchain_core_runnables.Runnable.html) protocol that most components implement.
This is a standard interface with a few different methods, which make it easy to define custom chains as well as making it possible to invoke them in a standard way. The standard interface exposed includes:

- [`stream`](/docs/expression_language/interface#stream): stream back chunks of the response
- [`invoke`](/docs/expression_language/interface#invoke): call the chain on an input
- [`batch`](/docs/expression_language/interface#batch): call the chain on a list of inputs
- [`streamLog`](/docs/expression_language/interface#stream-log): stream back intermediate steps as they happen, in addition to the final response
- [`streamEvents`](/docs/expression_language/interface#stream-events): **beta** stream events as they happen in the chain (introduced in `@langchain/core` 0.1.27)

The **input type** varies by component :

| Component      | Input Type                                          |
| -------------- | --------------------------------------------------- |
| Prompt         | Object                                              |
| Retriever      | Single string                                       |
| LLM, ChatModel | Single string, list of chat messages or PromptValue |
| Tool           | Single string, or object, depending on the tool     |
| OutputParser   | The output of an LLM or ChatModel                   |

The **output type** also varies by component :

| Component    | Output Type           |
| ------------ | --------------------- |
| LLM          | String                |
| ChatModel    | ChatMessage           |
| Prompt       | PromptValue           |
| Retriever    | List of documents     |
| Tool         | Depends on the tool   |
| OutputParser | Depends on the parser |

You can combine runnables (and runnable-like objects such as functions and objects whose values are all functions) into sequences in two ways:

- Call the `.pipe` instance method, which takes another runnable-like as an argument
- Use the `RunnableSequence.from([])` static method with an array of runnable-likes, which will run in sequence when invoked

See below for examples of how this looks.

## Stream

import StreamExample from "@examples/guides/expression_language/interface_stream.ts";

import IntegrationInstallTooltip from "@mdx_components/integration_install_tooltip.mdx";

<IntegrationInstallTooltip></IntegrationInstallTooltip>

```bash npm2yarn
npm install @langchain/openai
```

<CodeBlock language="typescript">{StreamExample}</CodeBlock>

## Invoke

import InvokeExample from "@examples/guides/expression_language/interface_invoke.ts";

<CodeBlock language="typescript">{InvokeExample}</CodeBlock>

## Batch

import BatchExample from "@examples/guides/expression_language/interface_batch.ts";

<CodeBlock language="typescript">{BatchExample}</CodeBlock>

You can also pass additional arguments to the call. The standard LCEL config object contains an option to set maximum concurrency,
and an additional `batch()` specific config object that includes an option for whether or not to return exceptions instead of throwing them (useful for gracefully handling failures!):

import BatchExampleWithOptions from "@examples/guides/expression_language/interface_batch_with_options.ts";

<CodeBlock language="typescript">{BatchExampleWithOptions}</CodeBlock>

## Stream log

All runnables also have a method called `.streamLog()` which is used to stream all or part of the intermediate steps of your chain/sequence as they happen.

This is useful to show progress to the user, to use intermediate results, or to debug your chain.
You can stream all steps (default) or include/exclude steps by name, tags or metadata.

This method yields [JSONPatch](https://jsonpatch.com/) ops that when applied in the same order as received build up the RunState.

To reconstruct the JSONPatches into a single JSON object you can use the [`applyPatch`](https://api.js.langchain.com/functions/langchain_core_utils_json_patch.applyPatch.html) method.
The example below demonstrates how to pass the patch to the `applyPatch` method.

Here's an example with streaming intermediate documents from a retrieval chain:

import StreamLogExample from "@examples/guides/expression_language/interface_stream_log.ts";

```bash npm2yarn
npm install @langchain/community @langchain/openai
```

<CodeBlock language="typescript">{StreamLogExample}</CodeBlock>

## Stream events

Event Streaming is a **beta** API, and may change a bit based on feedback. It provides a way to stream both intermediate steps and final output from the chain.

Note: Introduced in `@langchain/core` 0.1.27

For now, when using the `streamEvents` API, for everything to work properly please:

- Any custom functions / runnables must propragate callbacks
- Set proper parameters on models to force the LLM to stream tokens.

### Event Reference

Here is a reference table that shows some events that might be emitted by the various Runnable objects.
Definitions for some of the Runnable are included after the table.

⚠️ When streaming the inputs for the runnable will not be available until the input stream has been entirely consumed This means that the inputs will be available at for the corresponding `end` hook rather than `start` event.

| event                | name             | chunk                           | input                                         | output                                          |
| -------------------- | ---------------- | ------------------------------- | --------------------------------------------- | ----------------------------------------------- |
| on_chat_model_start  | [model name]     |                                 | {"messages": [[SystemMessage, HumanMessage]]} |                                                 |
| on_chat_model_stream | [model name]     | AIMessageChunk(content="hello") |                                               |                                                 |
| on_chat_model_end    | [model name]     |                                 | {"messages": [[SystemMessage, HumanMessage]]} | {"generations": [...], "llm_output": None, ...} |
| on_llm_start         | [model name]     |                                 | {'input': 'hello'}                            |                                                 |
| on_llm_stream        | [model name]     | 'Hello'                         |                                               |                                                 |
| on_llm_end           | [model name]     |                                 | 'Hello human!'                                |
| on_chain_start       | format_docs      |                                 |                                               |                                                 |
| on_chain_stream      | format_docs      | "hello world!, goodbye world!"  |                                               |                                                 |
| on_chain_end         | format_docs      |                                 | [Document(...)]                               | "hello world!, goodbye world!"                  |
| on_tool_start        | some_tool        |                                 | {"x": 1, "y": "2"}                            |                                                 |
| on_tool_stream       | some_tool        | {"x": 1, "y": "2"}              |                                               |                                                 |
| on_tool_end          | some_tool        |                                 |                                               | {"x": 1, "y": "2"}                              |
| on_retriever_start   | [retriever name] |                                 | {"query": "hello"}                            |                                                 |
| on_retriever_chunk   | [retriever name] | {documents: [...]}              |                                               |                                                 |
| on_retriever_end     | [retriever name] |                                 | {"query": "hello"}                            | {documents: [...]}                              |
| on_prompt_start      | [template_name]  |                                 | {"question": "hello"}                         |                                                 |
| on_prompt_end        | [template_name]  |                                 | {"question": "hello"}                         | ChatPromptValue(messages: [SystemMessage, ...]) |

import StreamEventsExample from "@examples/agents/stream_events.ts";

<CodeBlock language="typescript">{StreamEventsExample}</CodeBlock>

```
-----
Starting agent: Agent with input: {"input":"what is the weather in SF"}

-----
Starting tool: TavilySearchResults with inputs: weather in San Francisco

-----
Finished tool: TavilySearchResults

Tool output was: [{"title":"Weather in San Francisco","url":"https://www.weatherapi.com/","content":"Weather in San Francisco is {'location': {'name': 'San Francisco', 'region': 'California', 'country': 'United States of America', 'lat': 37.78, 'lon': -122.42, 'tz_id': 'America/Los_Angeles', 'localtime_epoch': 1707638479, 'localtime': '2024-02-11 0:01'}, 'current': {'last_updated_epoch': 1707638400, 'last_updated': '2024-02-11 00:00', 'temp_c': 11.1, 'temp_f': 52.0, 'is_day': 0, 'condition': {'text': 'Partly cloudy', 'icon': '//cdn.weatherapi.com/weather/64x64/night/116.png', 'code': 1003}, 'wind_mph': 9.4, 'wind_kph': 15.1, 'wind_degree': 270, 'wind_dir': 'W', 'pressure_mb': 1022.0, 'pressure_in': 30.18, 'precip_mm': 0.0, 'precip_in': 0.0, 'humidity': 83, 'cloud': 25, 'feelslike_c': 11.5, 'feelslike_f': 52.6, 'vis_km': 16.0, 'vis_miles': 9.0, 'uv': 1.0, 'gust_mph': 13.9, 'gust_kph': 22.3}}","score":0.98371,"raw_content":null},{"title":"San Francisco, California November 2024 Weather Forecast","url":"https://www.weathertab.com/en/c/e/11/united-states/california/san-francisco/","content":"Temperature Forecast Temperature Forecast Normal Avg High Temps 60 to 70 °F Avg Low Temps 45 to 55 °F Weather Forecast Legend WeatherTAB helps you plan activities on days with the least risk of rain. Our forecasts are not direct predictions of rain/snow. Not all risky days will have rain/snow.","score":0.9517,"raw_content":null},{"title":"Past Weather in San Francisco, California, USA — Yesterday or Further Back","url":"https://www.timeanddate.com/weather/usa/san-francisco/historic","content":"Past Weather in San Francisco, California, USA — Yesterday and Last 2 Weeks. Weather. Time Zone. DST Changes. Sun & Moon. Weather Today Weather Hourly 14 Day Forecast Yesterday/Past Weather Climate (Averages) Currently: 52 °F. Light rain. Overcast.","score":0.945,"raw_content":null},{"title":"San Francisco, California February 2024 Weather Forecast - detailed","url":"https://www.weathertab.com/en/g/e/02/united-states/california/san-francisco/","content":"Free Long Range Weather Forecast for San Francisco, California February 2024. Detailed graphs of monthly weather forecast, temperatures, and degree days.","score":0.92177,"raw_content":null},{"title":"San Francisco Weather in 2024 - extremeweatherwatch.com","url":"https://www.extremeweatherwatch.com/cities/san-francisco/year-2024","content":"Year: What's the hottest temperature in San Francisco so far this year? As of February 2, the highest temperature recorded in San Francisco, California in 2024 is 73 °F which happened on January 29. Highest Temperatures: All-Time By Year Highest Temperatures in San Francisco in 2024 What's the coldest temperature in San Francisco so far this year?","score":0.91598,"raw_content":null}]

-----
| The
|  current
|  weather
|  in
|  San
|  Francisco
|  is
|  partly
|  cloudy
|  with
|  a
|  temperature
|  of
|
| 52
| .
| 0
| °F
|  (
| 11
| .
| 1
| °C
| ).
|  The
|  wind
|  speed
|  is
|
| 15
| .
| 1
|  k
| ph
|  coming
|  from
|  the
|  west
| ,
|  and
|  the
|  humidity
|  is
|  at
|
| 83
| %.
|  If
|  you
|  need
|  more
|  detailed
|  information
| ,
|  you
|  can
|  visit
|  [
| Weather
|  in
|  San
|  Francisco
| ](
| https
| ://
| www
| .weather
| api
| .com
| /
| ).

-----
Finished agent: Agent

Agent output was: The current weather in San Francisco is partly cloudy with a temperature of 52.0°F (11.1°C). The wind speed is 15.1 kph coming from the west, and the humidity is at 83%. If you need more detailed information, you can visit [Weather in San Francisco](https://www.weatherapi.com/).

-----
```
